home *** CD-ROM | disk | FTP | other *** search
/ Amiga Plus 1997 #1 / Amiga Plus CD - 1997 - No. 01.iso / pd / programmierung / arexxport_dev / docs / arexxport.doc next >
Text File  |  1996-05-06  |  14KB  |  531 lines
  1. TABLE OF CONTENTS
  2.  
  3. arexxport.library/--RexxHost--
  4. arexxport.library/ArexxMacroAbort
  5. arexxport.library/ArexxMacroPending
  6. arexxport.library/CheckArexxPort
  7. ArexxPort.library/CloseArexxPort
  8. arexxport.library/LaunchArexx
  9. arexxport.library/OpenArexxPort
  10. Arexxport.library/PutToArexxPort
  11. arexxport.library/ReplyArexxPort
  12. arexxport.library/ReturnArexxError
  13. arexxport.library/SetArexxError
  14. Arexxport.library/SetArexxReturns
  15. arexxport.library/SetArexxReturnVar
  16. arexxport.library/SetArexxStem
  17. arexxport.library/--RexxHost--                 arexxport.library/--RexxHost--
  18.  
  19.    There is a single rexxhost function in this library.
  20.    The function is LocalErrorText() and it is a localised
  21.    version of the Arexx internal function ErrorText().
  22.    The arexx entry point to the library is at -108.
  23.    This function appeared in v37 of the library.
  24.  
  25.    EXAMPLE
  26.  
  27.     if ~show("L","arexxport.library") then
  28.         if ~addlib("arexxport.library", 37, -108) then exit
  29.  
  30.     say localerrortext( 19 )
  31.  
  32.  
  33.    NOTES
  34.      Created : 06/05/96
  35.  
  36.    BUGS
  37.  
  38.    SEE ALSO
  39.  
  40. arexxport.library/ArexxMacroAbort           arexxport.library/ArexxMacroAbort
  41.  
  42.    NAME
  43.      ArexxMacroAbort -- Set the abort flag for a port.
  44.  
  45.    SYNOPSIS
  46.      ArexxMacroAbort( port, all )
  47.                        a0    d0
  48.  
  49.      void ArexxMacroAbort( struct ArexxPort, BOOL )
  50.  
  51.    FUNCTION
  52.      Sets the abort flag for the given port and ports chained to it if
  53.      the 'all' flag is true. The abort flag is only set if a port
  54.      currently has any macro's pending. The abort flag is cleared
  55.      when the last macro returns.
  56.  
  57.    INPUTS
  58.      port - Port to set abort flag for.
  59.      all - If true, set abort flag for all chained ports.
  60.  
  61.    RESULT
  62.      None.
  63.  
  64.    EXAMPLE
  65.  
  66.    NOTES
  67.      Created : 17/06/95
  68.  
  69.    BUGS
  70.  
  71.    SEE ALSO
  72.  
  73. arexxport.library/ArexxMacroPending       arexxport.library/ArexxMacroPending
  74.  
  75.    NAME
  76.      ArexxMacroPending -- Checks if macros are pending from this port.
  77.  
  78.    SYNOPSIS
  79.      res = ArexxMacroPending( port )
  80.                                a0
  81.  
  82.      BOOL ArexxMacroPending( struct ArexxPort * )
  83.  
  84.    FUNCTION
  85.      Checks if any macros have been launched from this port (or any chained)
  86.      to it and not yet returned.
  87.  
  88.    INPUTS
  89.      port - Port to check.
  90.  
  91.    RESULT
  92.      res - TRUE if macros are pending. FALSE otherwise.
  93.  
  94.    EXAMPLE
  95.  
  96.    NOTES
  97.      Created : 20/03/96
  98.  
  99.    BUGS
  100.  
  101.    SEE ALSO
  102.  
  103. arexxport.library/CheckArexxPort             arexxport.library/CheckArexxPort
  104.  
  105.    NAME
  106.      CheckArexxPort -- Called to check if messages have arrived.
  107.  
  108.    SYNOPSIS
  109.      Arexxmsg = CheckArexxPort( port )
  110.                                  a0
  111.  
  112.      struct ArexxMsg * CheckArexxPort( struct ArexxPort )
  113.  
  114.    FUNCTION
  115.      Checks the given port (and those chained to it) for messages that
  116.      have arrived. Fills in a struct ArexxMsg with the details and returns
  117.      it. This function doesn't reply to the RexxMsg so a call to
  118.      ReplyArexxPort() is required after processing the ArexxMsg.
  119.  
  120.    INPUTS
  121.      port - The port to check.
  122.  
  123.    RESULT
  124.      ArexxMsg - a filled in arexxmsg structure.
  125.  
  126.    EXAMPLE
  127.  
  128.    NOTES
  129.      Created : 02/05/95
  130.      BUGFIX  : 06/10/95 Now checks all chained ports, regardless of
  131.                         the starting ports placement in the chain.
  132.  
  133.    BUGS
  134.  
  135.    SEE ALSO
  136.  
  137. ArexxPort.library/CloseArexxPort             ArexxPort.library/CloseArexxPort
  138.  
  139.    NAME
  140.      CloseArexxPort -- Close an arexx port.
  141.  
  142.    SYNOPSIS
  143.      CloseArexxPort( port )
  144.                       a0
  145.  
  146.      void CloseArexxPort( struct ArexxPort *)
  147.  
  148.    FUNCTION
  149.      Closes an arexx port opened with OpenArexxPort(). Will Guru if there
  150.      are any outstanding macros lauched from this port. Check before
  151.      closing. Using the MACROPENDING( port ) macro.
  152.  
  153.    INPUTS
  154.      port - Pointer to the port to close.
  155.  
  156.    RESULT
  157.      None
  158.  
  159.    EXAMPLE
  160.  
  161.    NOTES
  162.      Created : 02/05/95
  163.  
  164.    BUGS
  165.  
  166.    SEE ALSO
  167.  
  168. arexxport.library/LaunchArexx                   arexxport.library/LaunchArexx
  169.  
  170.    NAME
  171.      LaunchArexx -- Launches a arexx script.
  172.  
  173.    SYNOPSIS
  174.      invoc = *LaunchArexx( port, macro, console, user )
  175.                             a0    a1      d0      d1
  176.  
  177.      struct ArexxInvocation *LaunchArexx( struct ArexxPort *, STRPTR,
  178.                                           BOOL, ULONG )
  179.  
  180.    FUNCTION
  181.      Launches an arexx script from the given port. The script will return
  182.      an AREXX_MESSAGE a some point. The port must not be closed until the
  183.      script returns. Args for the script can be passed by joining them 
  184.      onto the macros name. 
  185.  
  186.    INPUTS
  187.      port - Pointer to the port to use as a default host.
  188.      macro - The name of the macro, ie "test.rexx".
  189.      console - If true then a console will be opened for the scripts output.
  190.      user - Data which is copied into the User_Data field of the
  191.             ArexxInvocation struct.
  192.  
  193.    RESULT
  194.      invoc - Pointer to an ArexxInvocation struct. NULL if this failed.
  195.  
  196.    EXAMPLE
  197.  
  198.    NOTES
  199.      Created : 15/10/95
  200.  
  201.    BUGS
  202.  
  203.    SEE ALSO
  204.  
  205. arexxport.library/OpenArexxPort               arexxport.library/OpenArexxPort
  206.  
  207.    NAME
  208.      OpenArexxPort -- Open a new arexx port for an application
  209.  
  210.    SYNOPSIS
  211.      Port = OpenArexxPort( portname, tags )
  212.                               a0      a1
  213.  
  214.      struct ArexxPort *OpenArexxPort( STRPTR, struct TagItem )
  215.  
  216.    FUNCTION
  217.      Opens a new arexx port for an application.
  218.  
  219.    INPUTS
  220.      portname - Basename of the port. This is copied, so doesn't have to
  221.        remain valid.
  222.      tags - The tags available are
  223.        ARLT_NOINSTANCE (BOOL)  - Just use the basename as the port name
  224.            don't put any (.##) number on the basename. (Default FALSE)
  225.            OpenPort will fail if this is given and a named port already
  226.            exists.
  227.        ARLT_COMMANDS - Pointer to command table list. Default NULL or if
  228.            command table from chained port. A pointer to this is stored
  229.            so it must remain valid. Default to none or the chained port.
  230.        ARLT_CONSOLE - Pointer to console def string. Default NULL or
  231.            console from chained port. Only a pointer is stored.
  232.        ARLT_CHAIN - Pointer to another ArexxLib port to chain this one
  233.            onto the end of. (Default NULL).
  234.        ARLT_EXTENSION - Pointer to a string containing the extension for
  235.            the default macros. Default none or the chained port's value.
  236.            Only a pointer is stored.
  237.        ARLT_USER (ULONG)  - User data.
  238.        ARLT_LASTERROR - Determines what should be done with error messages.
  239.            These errors are either generated internally by the command line
  240.            parsing or can be set by your program using the SetArexxError()
  241.            command. If this tags isn't given then the text of the error
  242.            message is written into the 'EXTERNERROR' variable in the arexx
  243.            script. If this tag is passed a pointer to a string then this
  244.            string will be used as the variable name instead of 'EXTERNERROR'.
  245.            ie ARLT_LASTERROR, "MULTIVIEW.LASTERROR". Only a pointer to this
  246.            string is stored and the string must be in uppercase.
  247.            If a NULL is pased then the text of the last error will in stored
  248.            and pointed to by the port->LastError. This allows the creation
  249.            of a 'lasterror' command for the port. The ports behaviour will
  250.            be the same as any chained port. (v37)
  251.  
  252.    RESULT
  253.      port - Pointer to the port or null if it failed.
  254.  
  255.    EXAMPLE
  256.  
  257.    NOTES
  258.      Created : 30/04/95
  259.      Bug fix in the chainport linking. 17 Aug 1995
  260.  
  261.    BUGS
  262.  
  263.    SEE ALSO
  264.  
  265. Arexxport.library/PutToArexxPort             Arexxport.library/PutToArexxPort
  266.  
  267.    >>>>>>>>>>>>>> Doesn't work yet <<<<<<<<<<<<<<<<<<<<<
  268.  
  269.    NAME
  270.      PutToArexxPort -- Puts a string to a named port.
  271.  
  272.    SYNOPSIS
  273.      Success = PutToArexxPort( port, msg )
  274.                                 a0    d1
  275.  
  276.      BOOL PutToArexxPort( STRPTR, STRPTR )
  277.  
  278.    FUNCTION
  279.  
  280.    INPUTS
  281.      port - The name of the public arexx port.
  282.      msg - The string of text to be sent.
  283.  
  284.    RESULT
  285.      Success - True is suceeds. False for a failure.
  286.  
  287.    EXAMPLE
  288.  
  289.    NOTES
  290.      Created : 17/06/95
  291.  
  292.    BUGS
  293.  
  294.  
  295.    SEE ALSO
  296.  
  297. arexxport.library/ReplyArexxPort             arexxport.library/ReplyArexxPort
  298.  
  299.    NAME
  300.      ReplyArexxPort -- Deallocates an ArexxMsg struct.
  301.  
  302.    SYNOPSIS
  303.      ReplyArexxPort( amsg )
  304.                       a0
  305.  
  306.      void ReplyArexxPort( struct ArexxMsg )
  307.  
  308.    FUNCTION
  309.      Deallocates an ArexxMsg structure and replies to the RexxMsg message
  310.      as required. This is a call that should match CheckArexxPort.
  311.  
  312.    INPUTS
  313.      amsg - The ArexxMsg struct to clear.
  314.  
  315.    RESULT
  316.      None.
  317.  
  318.    EXAMPLE
  319.  
  320.    NOTES
  321.      Created : 16/06/95
  322.  
  323.    BUGS
  324.  
  325.    SEE ALSO
  326.  
  327. arexxport.library/ReturnArexxError         arexxport.library/ReturnArexxError
  328.  
  329.    NAME
  330.      ReturnArexxError -- Returns the ports last error message. (v37)
  331.  
  332.    SYNOPSIS
  333.      result = ReturnArexxError( amsg )
  334.                                  a0
  335.  
  336.      UWORD ReturnArexxError( struct ArexxMsg * )
  337.  
  338.    FUNCTION
  339.      This returns the last error message of the port to the
  340.      rexx script. It will return the value in the RESULT field
  341.      of the message. Unless arg[0] of the ArexxMsg is set in which
  342.      case that string will be used as a a variable name. This is the
  343.      command to call if you wish to implement a LastError or Fault
  344.      command - in combination with the ARLV_LASTERROR = NULL.
  345.  
  346.    INPUTS
  347.      amsg - The message.
  348.  
  349.    RESULT
  350.      Returns 0 for success.
  351.      Non zero for failure.
  352.  
  353.    EXAMPLE
  354.  
  355.        struct ArexxFunction mainctab[] = {
  356.            ...
  357.            {"lasterror", &ReturnArexxError, "VAR" },
  358.        The user call this command to find why the last command
  359.        failed. The text of the error will be returned in RESULT
  360.        or in VAR if the user suppiles one.
  361.  
  362.            {NULL,NULL,NULL},
  363.        };
  364.        ...
  365.  
  366.             while( amsg = CheckArexxPort( MainRexxPort) ) {
  367.                 if(amsg->Type == AREXX_COMMAND) {
  368.                     void (*target)( struct ArexxMsg *msg );
  369.                     target = (void *)amsg->User_Data;
  370.                     target( amsg );
  371.                 }
  372.                 ReplyArexxPort( amsg );
  373.             }
  374.  
  375.  
  376.    NOTES
  377.      Created : 07/04/96
  378.  
  379.    BUGS
  380.  
  381.    SEE ALSO
  382.  
  383. arexxport.library/SetArexxError               arexxport.library/SetArexxError
  384.  
  385.    NAME
  386.      SetArexxError -- Return an error to the arexx script.
  387.  
  388.    SYNOPSIS
  389.      SetArexxError( Amsg, error, level )
  390.                      a0     a1    d0
  391.  
  392.      void SetArexxError( struct ArexxMsg, STRPTR, UWORD )
  393.  
  394.    FUNCTION
  395.      Sets the RC of a command. The passed error message is either
  396.      stored in port->LastError, written into the rexx variable or
  397.      into 'EXTERNERROR' (see OpenArexxPort - ARLT_LASTERROR for
  398.      details.)
  399.  
  400.    INPUTS
  401.      Amsg - Command to fail.
  402.      error - The text of the error message.
  403.      level - The level of the RC for the error.
  404.  
  405.    RESULT
  406.      None.
  407.  
  408.    EXAMPLE
  409.  
  410.    NOTES
  411.      Created : 16/06/95
  412.  
  413.    BUGS
  414.  
  415.    SEE ALSO
  416.  
  417. Arexxport.library/SetArexxReturns           Arexxport.library/SetArexxReturns
  418.  
  419.    NAME
  420.      SetArexxReturns -- Set the return values.
  421.  
  422.    SYNOPSIS
  423.      SetArexxReturns( msg, rc, r2 )
  424.                       a0   d0  a1
  425.  
  426.      void SetArexxReturns( struct ArexxMsg *, UWORD, APTR )
  427.  
  428.    FUNCTION
  429.      Sets the value of the return codes for the given Arexxmsg.
  430.      If rc is not 0 then Arexx will not set the RESULT variable.
  431.      This is not a bug but a feature of Arexx.
  432.  
  433.    INPUTS
  434.      msg - ArexxMsg to set return codes for.
  435.      rc - Value of return code 1. (RC a number.)
  436.      r2 - String to put in result string. requires Options Results to be
  437.           set.
  438.  
  439.    RESULT
  440.      None.
  441.  
  442.    EXAMPLE
  443.  
  444.    NOTES
  445.      Created : 16/06/95
  446.  
  447.    BUGS
  448.  
  449.    SEE ALSO
  450.  
  451. arexxport.library/SetArexxReturnVar       arexxport.library/SetArexxReturnVar
  452.  
  453.    NAME
  454.      SetRexxReturnVar -- Sets the return values. (v37)
  455.  
  456.    SYNOPSIS
  457.      result = SetArexxReturnVar( amsg, rc, r2, var )
  458.                                 a0    d0  a1  a2
  459.  
  460.      UWORD SetArexxReturnVar( struct ArexxMsg *, UWORD, STRPTR, STRPTR )
  461.  
  462.    FUNCTION
  463.      Sets the RC and RESULT values of a message, like SetArexxReturn()
  464.      however if var is non NULL the r2 value will be written into the
  465.      the variable named. This is to make it easy to implement the 'VAR'
  466.      command option for returning values.
  467.  
  468.    INPUTS
  469.      amsg - Arexx msg to set values into.
  470.      rc - Primary Return code.
  471.      r2 - Secondary string.
  472.      var - Variable to write r2 into or NULL.
  473.  
  474.    RESULT
  475.      Non NULL for a failure, zero for sucess.
  476.  
  477.    EXAMPLE
  478.  
  479.    NOTES
  480.      Created : 08/04/96
  481.  
  482.    BUGS
  483.  
  484.    SEE ALSO
  485.  
  486. arexxport.library/SetArexxStem                 arexxport.library/SetArexxStem
  487.  
  488.    NAME
  489.      SetArexxStem -- Set a stem variable in arexx.
  490.  
  491.    SYNOPSIS
  492.      error = SetArexxStem( stem, exten, setto, msg )
  493.                     a0     a1     a2    a3
  494.  
  495.      LONG SetArexxStem( STRPTR, STRPTR, STRPTR, struct RexxMsg )
  496.  
  497.    FUNCTION
  498.      This function will sttempt to set the value of the symbol
  499.      stem.exten in the Arexx script that sent the message.
  500.  
  501.    INPUTS
  502.      stem - Stem part of the variable.
  503.      exten - The extention part of the variable.
  504.      setto - A string that will be the new value of the variable.
  505.      msg - The RexxMsg that variable refers to.
  506.  
  507.    RESULT
  508.      error     0 for sucess, otherwise an error vode.
  509.                (Other codes may exist these are documented).
  510.                3  == Insufficient Storage.
  511.                9  == String too Long.
  512.                10 == Invalid message.
  513.  
  514.    EXAMPLE
  515.        if( SetArexxStem( "fish","count","120", msg ) != 0 ) {
  516.            /* An error has occured */
  517.        } else {
  518.            /* Variable 'fish.count' = 120 */
  519.        }
  520.  
  521.    NOTES
  522.      Created : 16/06/95
  523.      Removed limitations and added return code for v37 : 12/4/96
  524.       v36 libraries don't set the return code.
  525.  
  526.    BUGS
  527.  
  528.    SEE ALSO
  529.      amiga.lib/SetRexxVar()
  530.  
  531.